home *** CD-ROM | disk | FTP | other *** search
/ PC Media 3 / PC MEDIA CD03.iso / share / os2 / psrt_14 / pktsort.doc < prev    next >
Encoding:
Text File  |  1994-04-25  |  39.8 KB  |  1,004 lines

  1.  
  2.  
  3.  
  4.   PacketSorter v1.4                                         page 1/19
  5.  
  6.  
  7.                              PacketSorter v1.4
  8.                     Copyright 1993, 1994 Rolf K. Wilms
  9.  
  10.  
  11.  
  12.   Key Features
  13.   ------------
  14.  
  15.  
  16.   -   defragment FidoNet mail packets for up to 5 times faster tossing
  17.  
  18.   -   split and unsplit large messages to fit your systems limits
  19.  
  20.   -   sort messages by subject and/or time for easy thread-following
  21.  
  22.   -   break down large inbound packets to a handy size
  23.  
  24.   -   remove the garbage from 'bad' packets
  25.  
  26.   -   operates stand-alone or can be called from echomail tosser
  27.  
  28.   -   32-BIT OS/2 and DOS version (needs i386 or higher)
  29.  
  30.  
  31.  
  32.   PacketSorter v1.4                                         page 2/19
  33.  
  34.  
  35.  
  36.  
  37.   Contents of this document
  38.   -------------------------
  39.  
  40.   1.Brief license and warranty information ......................3
  41.   2.A warning ...................................................3
  42.   3.System requirements .........................................3
  43.   4.Introduction ................................................4
  44.   5.Installation ................................................5
  45.       As a VCPI client ..........................................5
  46.       As a DPMI client ..........................................5
  47.       Under OS/2 ................................................5
  48.       Quick installation for Squish users .......................6
  49.       Quick installation for CrossPoint users ...................6
  50.       Quick installation for IMail users ........................7
  51.       Quick installation for FastEcho users .....................8
  52.       Installation for users of other tossers ...................9
  53.   6.Ways of configuration .......................................9
  54.   7.Command line options ........................................10
  55.       -c<file>   configuration file name ........................10
  56.       -w<count>  number of messages to keep in memory ...........10
  57.       -s<size>   limit in bytes for (un)splitting messages ......10
  58.       -p<count>  max. number of messages in output packets ......11
  59.       -otime     sort messages by time ..........................11
  60.       -osubject  sort messages by subject and time ..............11
  61.       -g<size>   remove garbage from packets ....................11
  62.       -e<entry>  select Archiver entry from cfg file ............12
  63.       -l<file>   log file name ..................................12
  64.       -d<dir>    directory where packets are searched ...........13
  65.       -h         help ...........................................13
  66.       [program-with-args]  exec. archiver before processing .....13
  67.   8. Setting the options via an environment variable ............13
  68.   9. Setting the options via a configuration file ...............14
  69.   10.Packets recognized and created .............................14
  70.   11.Return codes ...............................................15
  71.   12.Disk space consumption .....................................15
  72.   13.Removing garbage from packets ..............................15
  73.   14.Technology .................................................16
  74.   15.What is different in the registered version ................16
  75.   16.Other operating systems ....................................17
  76.       native MS-Windows .........................................17
  77.       Linux/Unix/Nextstep .......................................17
  78.   17.Author .....................................................17
  79.   18.Contents of the distribution archives ......................18
  80.   19.Thanks .....................................................19
  81.  
  82.  
  83.  
  84.   PacketSorter v1.4                                         page 3/19
  85.  
  86.  
  87.  
  88.   1. Brief license and warranty information
  89.   -----------------------------------------
  90.  
  91.   You may  copy  and  distribute  the  unmodified  distribution  archives
  92.   (PSRT_14.ZIP) as you receive it in any medium.
  93.  
  94.   You may use PacketSorter for testing if it is of value to you. You must
  95.   not use  PacketSorter for  more than  30  days without  registering it.
  96.   After a period of  30 days you  must either stop  using PacketSorter or
  97.   register. Look  at  the  file  'ORDER.FRM'  on  how  to  register.  The
  98.   registration fee is US $15.
  99.  
  100.   There is no warranty.
  101.  
  102.   Please read the file 'license.doc' for details.
  103.  
  104.  
  105.   2. A warning
  106.   ------------
  107.  
  108.   This version of  PacketSorter has only  been tested on  a few different
  109.   systems, as  it  is any  time  when  a new  public  release  comes out.
  110.   Although PacketSorter  performed well  on these    systems there  is no
  111.   guarantee that it does  not break yours. It  is no bad idea  to back up
  112.   your mail packets before you try PacketSorter the first time.
  113.  
  114.  
  115.   3. System requirements
  116.   ----------------------
  117.  
  118.   Operating system:  OS/2 2.x
  119.                      or DOS 3.0 or higher
  120.  
  121.   Processor:         i386 or higher
  122.  
  123.   Memory:            A minimum of 2MB is needed for DOS
  124.  
  125.  
  126.  
  127.   PacketSorter v1.4                                         page 4/19
  128.  
  129.  
  130.  
  131.   4. Introduction
  132.   ---------------
  133.  
  134.   PacketSorter is  a utility  for defragmenting,  splitting, unsplitting,
  135.   cleaning and sorting inbound FidoNet (FTS-0001) message packets. It has
  136.   been developed in the first place  because the time the echomail tosser
  137.   Squish needs to toss messsages into  the messagebase heavily depends on
  138.   the fragmentation  level  of  the  packets  received.  The packets  you
  139.   receive  from  your  links  are  usually   not  sorted  in  any  order.
  140.   PacketSorter groups the messages contained in the packets by their area
  141.   tag. On my system the packets defragmented with PacketSorter are tossed
  142.   by Squish  up  to  5  times  faster  than  the  original  packets.  The
  143.   performance gain you  will notice  depends on the  tosser you  use, the
  144.   messagebase you use and the performance  of your disk subsystem. People
  145.   using a Hudson-style messagebase or a hardware cache controller for the
  146.   harddisk may notice  no performance  gain at  all. PacketSorter  is not
  147.   limited to be used only with Squish.  You may use PacketSorter with any
  148.   other echomail processor.
  149.  
  150.   FTS-0001 specifies  no limit  to the  size  of messages.  Some echomail
  151.   processors crash if  they're fed  with messages  that exceed  a certain
  152.   size or those messages get dumped.  The following echomail tosssers are
  153.   said to have limits:
  154.  
  155.   GroupMail      8K
  156.   QMail         16K
  157.   ConfMail      14K
  158.   QEcho         10K
  159.   TosScan       32K
  160.   Squish        16K
  161.   FastEcho      64K (configurable)
  162.  
  163.   PacketSorter can  split and  unsplit large  messages according  to FSC-
  164.   0047, so that  your echomail  processor operates well.  Systems capable
  165.   processing large  messages  can  get  the  messages  unsplit  to  their
  166.   original size. See option -s.
  167.  
  168.   Large inbound packets  can be  broken down  into several  smaller ones.
  169.   Some echomail processors benefit from this  by saving disk space during
  170.   tossing for  downlinks.  If  packets are  considered  as  "bad"  by the
  171.   echomail processor  you may  like to  have  smaller packets  to examine
  172.   manually.
  173.  
  174.   Messages within the echo areas can be sorted  by subject and time or by
  175.   time only.  Sorting  by time  usually  does not  "look"  different from
  176.   unsorted messages when  you list the  messages in your  mail reader but
  177.   helps to put original  messages before the replies.  Sorting by subject
  178.   and time does look  different: all messages with  identical subject are
  179.   grouped together so you  can quickly see  what's going on  in a thread.
  180.   See options -otime, -osubject.
  181.  
  182.  
  183.  
  184.   PacketSorter v1.4                                         page 5/19
  185.  
  186.  
  187.   Sometimes you receive packets not only containig messages but also some
  188.   "garbage". This garbage is introduced by  poor software or transmission
  189.   errors. The consequence of  such "grunged" packets is  that your tosser
  190.   complains about "grunged messages",  "data beyond logical  end of file"
  191.   or just loses messages. PacketSorter can clean such packets by throwing
  192.   out the garbage, thus  creating proper packets.  Proper messages before
  193.   and following a bad chunk will not be lost. Messages beyond the logical
  194.   end of file will be recovered. Grunged  packets can be renamed to *.bad
  195.   depending on  the amount  of garbage  removed.  See option  -g  and the
  196.   section 'Removing garbage from packets' for details.
  197.  
  198.  
  199.   5. Installation
  200.   ---------------
  201.  
  202.   PacketSorter can be run in three different environments (DOS-VCPI, DOS-
  203.   DPMI and OS/2). There  are two DOS extenders  (emx.exe and rsx.exe) and
  204.   one DLL (emx.dll for OS/2) packed with PacketSorter in the distribution
  205.   archives.
  206.  
  207.  
  208.   As a VCPI client
  209.   ----------------
  210.  
  211.     This is the 'normal' mode  under DOS. Make sure  that you either have
  212.     EMM386.EXE installed with EMS or don't  have EMM386.EXE installed. If
  213.     you have EMM386 installed  without providing EMS memory  you will see
  214.     an error message 'Virtual mode not supported without VCPI'.
  215.  
  216.     The VCPI mode uses  the file emx.exe.  Make sure that  emx.exe can be
  217.     found in one of the directories of the PATH.
  218.  
  219.     You may  look  at  the  file  emxinst.doc  for advanced  installation
  220.     options available for the EMX DOS extender.
  221.  
  222.  
  223.  
  224.   As a DPMI client
  225.   ----------------
  226.  
  227.     This is to  use if you  want PacketSorter to  run in  Windows or OS/2
  228.     DOS-emulation (DOS box). PacketSorter  needs the file  RSX.EXE to run
  229.     as a DPMI client. Make sure  that rsx.exe can be found  in one of the
  230.     directories of the  PATH and add  the following  to your environment:
  231.     RSXOPT=-e
  232.     You can do this by putting the following line in your autoexec.bat:
  233.     SET RSXOPT=-e
  234.     If you forget to  set up the environment  variable RSXOPT, you'll get
  235.     an error message 'Can't find rsx387' when you start PacketSorter.
  236.  
  237.     You may  look  at  the  file  rsxinst.doc  for advanced  installation
  238.     options available for the RSX DOS extender.
  239.  
  240.  
  241.  
  242.   PacketSorter v1.4                                         page 6/19
  243.  
  244.  
  245.   Under OS/2
  246.   ----------
  247.  
  248.     Copy emx.dll to \os2\dll
  249.  
  250.     You may  look  at  the  file  emxinst.doc  for advanced  installation
  251.     options available for the EMX runtime system.
  252.  
  253.  
  254.  
  255.  
  256.  
  257.   Quick installation for Squish users
  258.   -----------------------------------
  259.  
  260.     Follow the instructions for setting up PacketSorter to run as a DPMI,
  261.     VCPI or OS/2  client. Make sure  that Squish  can swap  to disk (swap
  262.     keyword in squish.cfg).
  263.  
  264.     Copy PKTSORT.EXE in your Squish directory.
  265.  
  266.     Edit the EXTRACT commands in your compress.cfg file:
  267.  
  268.     Insert 'pktsort -s15000 -p500' before each call to an unpacker.
  269.     Examples:
  270.  
  271.     OS2    Extract   unzip -n %a %f
  272.     becomes
  273.     OS2    Extract   pktsort -s16000 -p500 unzip -n %a %f
  274.  
  275.     OS2    Extract   doswrap pkunzip -n %a %f
  276.     becomes
  277.     OS2    Extract   pktsort -s16000 -p500 doswrap pkunzip -n %a %f
  278.  
  279.     DOS    Extract   pkunzip -n %a %f
  280.     becomes
  281.     DOS    Extract   pktsort -s16000 -p500 pkunzip -n %a %f
  282.  
  283.     If your system has less than 2 MB of free memory above the first
  284.     megabyte, please read the section about the command line option -w in
  285.     this document.
  286.  
  287.  
  288.   Quick installation for CrossPoint users
  289.   ---------------------------------------
  290.  
  291.     Follow the instructions for setting up PacketSorter to run as a DPMI
  292.     or VCPI client.
  293.  
  294.     Copy PKTSORT.EXE to your CrossPoint directory.
  295.  
  296.     For each Fido-Box you have set up in 'Edit/Boxen' do the following:
  297.  
  298.  
  299.  
  300.   PacketSorter v1.4                                         page 7/19
  301.  
  302.  
  303.     Select 'Edit/Point'  (in  'Edit/Boxen'). In  the  dialog,  change the
  304.     'Download-Packer' entry by inserting '\xp\pktsort -s256000 -osubject'
  305.     before the  call  to  the packer  (this  assumes  that  CrossPoint is
  306.     located in \XP).
  307.  
  308.     Example:
  309.  
  310.     pkunzip $DOWNFILE
  311.     becomes
  312.     \xp\pktsort -s256000 -osubject pkunzip $DOWNFILE
  313.  
  314.     As CrossPoint has no (known) limits to the size of messages that can
  315.     be processed, the setting -s256000 will only split messages that
  316.     exceed 265000 bytes and all already split messages that are smaller
  317.     will be unsplit, so that you get most of the messages back to their
  318.     original size.
  319.     This is useful if you get Usenet news via a Usenet/Fidonet gateway. A
  320.     lot of messages from the Usenet  get split at the gateway, especially
  321.     large  UUENCODED  files.  Having  these  messages  unsplit  to  their
  322.     original size, you can directly UUDECODE  them from within CrossPoint
  323.     without unsplitting them manually.
  324.  
  325.     The setting -osubject sorts the messages by subject.
  326.  
  327.     If you want to  use different options, refer  to the section 'Command
  328.     line options' in this document.
  329.  
  330.     If your system  has less  than 2 MB  of free  memory above  the first
  331.     megabyte, please read the section about the command line option -w in
  332.     this document.
  333.  
  334.  
  335.  
  336.   Quick installation for IMail users
  337.   ----------------------------------
  338.  
  339.     Follow the instructions for setting up  PacketSorter to run as a DPMI
  340.     or VCPI client.
  341.  
  342.     Copy  PKTSORT.EXE   to  your   IMail  directory.   Copy   the  sample
  343.     configuration file pktsort.cfg in your IMail directory. You will have
  344.     to edit the configuration file in a later step.
  345.  
  346.     Set up the environment variable PKTSORT and specify the configuration
  347.     to be used. Best is to include this in your AUTOECEC.BAT like that:
  348.  
  349.     SET PKTSORT=-cc:\imail\pktsort.cfg
  350.  
  351.     Edit the configuration file pktsort.cfg. You will have to set up some
  352.     Archiver definitions  for the  archiver (decompression)  programs you
  353.     use:
  354.  
  355.     Eg. (add this to the configuration file):
  356.  
  357.     Archiver ARJ c:\tools\arj.exe
  358.  
  359.  
  360.  
  361.   PacketSorter v1.4                                         page 8/19
  362.  
  363.  
  364.     Archiver ZIP c:\tools\pkunzip.exe
  365.     Archiver LHA c:\tools\lha.exe
  366.     Archiver GUS c:\tools\gus.exe
  367.  
  368.     Now run Imsetup to  change the decompression program  settings in the
  369.     following way: in  each decompression program  definition replace the
  370.     name of the decompression program by  PKTSORT.EXE -eKEY, where KEY is
  371.     the abbreviation  for the  Archiver definition  in  the configuration
  372.     file.
  373.  
  374.     Examples:
  375.  
  376.     ARJ      ARJ.EXE e -y
  377.     becomes
  378.     ARJ      PKTSORT.EXE -eARJ e -y
  379.  
  380.     PkZip    PkunZip.exe -o -ed
  381.     becomes
  382.     PkZip    PKTSORT.EXE -eZIP -o -ed
  383.  
  384.     You may edit the other settings in pktsort.cfg to fit your needs.
  385.  
  386.     Thanks  to  Johann  H.  Addicks  for   finding  out  how  to  set  up
  387.     PacketSorter in IMail.
  388.  
  389.  
  390.  
  391.   Quick installation for FastEcho users
  392.   -------------------------------------
  393.  
  394.     Follow the instructions for setting up  PacketSorter to run as a DPMI
  395.     or VCPI client.
  396.  
  397.     Copy PKTSORT.EXE to your FastEcho directory.
  398.  
  399.     Start FESetup and look which directory  is set up as the TEMP-INBOUND
  400.     directory  for  FastEcho.  You'll  find  this  setting  in  the  menu
  401.     SYSTEM/PATHNAMES/Temp.  Inb.  If   there  is   no  temporary  inbound
  402.     directory specified, please  choose one,  because the  way installing
  403.     PacketSorter for FastEcho is  described here will not  work without a
  404.     temp. inbound directory.
  405.  
  406.     Check the maximum message size you  have configured for FastEcho. You
  407.     can find  the  value in  SYSTEM/PARAMETERS/MESSAGEBUFFERSIZE.  If the
  408.     value there is zero, it means a maximum message size of 32000.
  409.  
  410.     Now change to the dialog where  the decompession programs are set up.
  411.     It's in SYSTEM/DECOMPRESSION PROGRAMS.
  412.  
  413.     Change each decompression  program definition  in the  following way:
  414.     preceed  each   definition  with   'PKTSORT.EXE   -d<temp-inbound>  -
  415.     s<max_message>'.  <temp-inbound>  is  the  directory  you  looked  up
  416.     before. <max_message>  is  the  maximum message  size  you  looked up
  417.     before minus 1000 (for additional SEEN-BYs etc.).
  418.  
  419.  
  420.  
  421.   PacketSorter v1.4                                         page 9/19
  422.  
  423.  
  424.     Examples:
  425.  
  426.     I assume your temporary inbound directory is c:\fastecho\temp and the
  427.     maximum message size is 32000.
  428.  
  429.     The decompression program definitions look like this:
  430.  
  431.     PKZip       PkunZip.Exe -o -ed
  432.     becomes
  433.     PKZip       PKTSORT.EXE -dc:\fastecho\temp -s31000 PkunZip.exe -o -ed
  434.  
  435.     LHa         LHa.Exe e -m1
  436.     becomes
  437.     LHa         PKTSORT.EXE -dc:\fastecho\temp -s31000 LHa.exe e -m1
  438.  
  439.     ARJ         arj e -y
  440.     becomes
  441.     ARJ         PKTSORT.EXE -dc:\fastecho\temp -s31000 arj.exe e -y
  442.  
  443.  
  444.     Other options to PKTSORT.EXE may be specified before the name of the
  445.     decompression program. Example:
  446.  
  447.     ARJ  PKTSORT.EXE -dc:\fastecho\temp -s31000 -g3000 -osubject arj.exe
  448.     e -y
  449.  
  450.     Another way to specify additional options to PacketSorter is to use a
  451.     configuration file. Copy pktsort.cfg into the FastEcho directory and
  452.     edit it to your needs.
  453.  
  454.  
  455.  
  456.   Installation for users of other tossers
  457.   ---------------------------------------
  458.  
  459.     PacketSorter needs  to be  run on  inbound  packets, i.e.  before the
  460.     packets  are  tossed.  Usually,  inbound   packets  are  received  in
  461.     compressed form in archives. Many tossers  are smart enough to unpack
  462.     the archives  by  calling  an  uncompression  utility  which you  may
  463.     specify in the  tosser setup. This  is the  point where  to 'hook' up
  464.     PacketSorter: you  specify PacketSorter  as an  uncompression program
  465.     and let PacketSorter first call the  'real' uncompression program and
  466.     then process the uncompressed packets. This way only packets received
  467.     in compressed form will be processed  by PacketSorter. If you want to
  468.     process packets received uncompressed  too, start PacketSorter before
  469.     starting the  tosser without  specifying an  archiver.  See [program-
  470.     with-args] in the 'Command line options' section of this document for
  471.     further explaination.
  472.  
  473.     If you don't let your tosser unpack the archives, for example because
  474.     you  use  an  archiver  shell  like  GUS  before  tossing,  just  run
  475.     PacketSorter from the batch file after unpacking the archives.
  476.  
  477.  
  478.  
  479.   PacketSorter v1.4                                         page 10/19
  480.  
  481.  
  482.   6. Ways of configuration
  483.   ------------------------
  484.  
  485.   PacketSorter can be configured  in three different ways.  One is to use
  486.   command line parameters, the  second is to use  an environment variable
  487.   and the third is to use a  configuration file. Theese three methods can
  488.   be combined. If a configuration  option is set by  more than one method
  489.   the following  rule  determines  which one  will  be  used: environment
  490.   setting overrides configuration  file setting and  command line setting
  491.   overrides environment setting.
  492.  
  493.   Archiver entries can only be defined in the configuration file.
  494.  
  495.  
  496.   7. Command line options
  497.   -----------------------
  498.  
  499.   Syntax:
  500.   pktsort[-c<file>] [-w<count>] [-s<size>] [-p<count>]
  501.          [-osubject | -otime] [-l<file>] [-d<dir>]
  502.          [-g<size>] [-h] [-e<entry> [args] | program-with-args]
  503.  
  504.  
  505.  
  506.   -c<file> configuration file name
  507.  
  508.     Specify  the  name  of   the  configuration  file.   The  default  is
  509.     "pktsort.cfg" which is searched  in the current  directory. Note that
  510.     the current  directory is  not neccessarily  the  same as  that where
  511.     PKTSORT.EXE is located. If you want to be sure that the configuration
  512.     file  can  allways  be  found,  use   the  full  path  and  filename.
  513.     PacketSorter does  not  complain if  the  default  configuration file
  514.     cannot be found,  only if  a configuration file  explicitly specified
  515.     with -c cannot be found.
  516.  
  517.  
  518.   -w<count>number of messages to keep in memory
  519.  
  520.     Specify the size of the message window, that is the maximum number of
  521.     messages  to  keep   in  main   memory  during   defragmentation  and
  522.     subject/time sorting. If this  number is less than  the actual number
  523.     of  messages  to  process,   the  messages  can   only  be  partially
  524.     defragmented or sorted.  The default  size is  1000. With  an average
  525.     message size of 1.3 kbytes a  maximum of 1.3 MB  of main memory would
  526.     be used for messages. Do not specify a size that would need more than
  527.     your free  memory, because  your system  would  then start   swapping
  528.     memory to disk, yielding very poor  performance (this applies both to
  529.     DOS and  OS/2!). A  <count>  of 1  means  no defragmentation/sorting.
  530.     (Un)Splitting messages and packets and  removing garbage from packets
  531.     still works fine with a <count> of 1.
  532.  
  533.  
  534.  
  535.   -s<size> limit in bytes for (un)splitting messages
  536.  
  537.  
  538.  
  539.   PacketSorter v1.4                                         page 11/19
  540.  
  541.  
  542.     Enable message  splitting  and  unsplitting  according  to  FSC-0047.
  543.     Messages larger than <size> are split  into smaller parts. Message-id
  544.     kludges are stripped  from all parts  but the first  to prevent those
  545.     parts to  be killed  by dupe  detection.  Messages which  are already
  546.     split according to  FTS-0047 will be  unsplit internally  and will be
  547.     re-split if the size of the unsplit messages exceeds <size>. Incoming
  548.     split messages can only be unsplit if all split parts are seen during
  549.     a run  of  PacketSorter.  Messages split  multiple  times,  as  it is
  550.     possible with versions of  PacketSorter up to v1.1b,  will be unsplit
  551.     'recursivly'. The  default is  no splitting/unsplitting.  The minimum
  552.     <size> is 8000. Use the maximum message size minus 1000 (for SEEN-BYs
  553.     etc.) your system can handle for <size>.
  554.  
  555.  
  556.  
  557.   -p<count>max. number of messages in output packets
  558.  
  559.     Create several smaller  output packets  instead of one  large packet.
  560.     <count> is the maximum number of messages  to put into one packet. If
  561.     a message  is split  into several  parts,  these parts  count  as one
  562.     message in this context. The default is 1000.
  563.  
  564.  
  565.  
  566.   -otime   sort messages by time
  567.  
  568.     Sort messages within the areas by their creation time. This will help
  569.     keeping original messages before their replies. The sorting will only
  570.     affect as much  messages as  are kept  internally (as  specified with
  571.     option -w). If  not all messages  to process are  kept internally the
  572.     sorting will only be partial.
  573.  
  574.  
  575.  
  576.   -osubjectsort messages by subject and time
  577.  
  578.     Sort messages within the  areas by their subject.  This will help you
  579.     to follow echomail  threads with  your message reader.  Messages with
  580.     identical subject are sorted by their  creation time. Leading 'Re: ',
  581.     'Re^2:' etc. in the  subject line are ignored  while sorting, so that
  582.     messages containing a 'Re:'  in the subject appear  near the messages
  583.     with the original subject.  Complete sorting is only  possible if all
  584.     messages to process can be kept internally (see option -w and comment
  585.     in option -otime).
  586.     Please note: while you may like the messages sorted by their subject,
  587.     others may  prefer the  'unordered' style.  If  you have  other nodes
  588.     linked to your system  and sort the messages  by subject, be prepared
  589.     that one or the other node complains about the new look.
  590.  
  591.  
  592.  
  593.   -g<size> remove garbage from packets
  594.  
  595.  
  596.  
  597.   PacketSorter v1.4                                         page 12/19
  598.  
  599.  
  600.     With this option, PacketSorter  will remove garbage  from bad packets
  601.     instead of refusing  to process  them. If garbage  is removed  from a
  602.     packet, PacketSorter  exactly reports  which packet  it is,  where it
  603.     came from and  which portions  of the packet  have been  removed. The
  604.     original packets may automatically be saved by renaming them to *.bad
  605.     (or  *.b00,  *.b01  etc.  if  the  file  already  exists)  for  later
  606.     examination. You can control if a "bad" packet is renamed to *.bad by
  607.     the value  you  specify for  <size>.  If more  than  <size>  bytes of
  608.     garbage have  been removed  from the  packet, it  will be  renamed to
  609.     *.bad. Thus, -g0  will rename any  packet with removed  garbage and -
  610.     g999999999 is probably  enough to  disable renaming completly.  So if
  611.     you don't care about say 3000 lost bytes, you specify -g3000. If more
  612.     than 3000 bytes are removed, you'll  have the original packet renamed
  613.     for later examination. The valid portions in the packet are processed
  614.     in any case, not regarding whether the  packet is renamed to *.bad or
  615.     not. See section 'Removing garbage from packets' in this document for
  616.     further details.
  617.  
  618.  
  619.   -e<entry>select Archiver entry from cfg file
  620.  
  621.     This option  selects  an  Archiver  entry  which  is  defined in  the
  622.     configuration file.  <entry> is  the key  which selects  the Archiver
  623.     entry from the configuration file. -e<entry> must allways be the last
  624.     option to PacketSorter. Options following -e<entry> will only be seen
  625.     by the uncompression  program selected. When  PacketSorter is defined
  626.     as an archiver program in the echomail tosser, usually [program-with-
  627.     args] is  used to  tell PacketSorter  which uncompression  program to
  628.     call before processing  packets. Some  echomail tossers  (like IMail)
  629.     strip all paths from their uncompression program definitions, so that
  630.     specifying a path to the uncompression program in [program-with-args]
  631.     is not  possible. One  way to  get around  this  would be  to specify
  632.     [program-with-args] in the PKTSORT environment variable, but this way
  633.     only one uncompression  program could  be specified which  is usually
  634.     not enough. Using  -e<entry>, a  complete archiver definition  can be
  635.     retrieved  from  the  configuration  file.   Options  needed  by  the
  636.     uncompression program  may  follow  -e<entry>.  Here  is an  example:
  637.     Assume  you   have   the  following   Archiver   definition   in  the
  638.     configuration file:
  639.  
  640.     Archiver UNZIP c:\packer\unzip.exe
  641.  
  642.     and the uncompression program definition in the tosser is
  643.  
  644.     unzip -d %a %f
  645.  
  646.     Then you can use
  647.  
  648.     PKTSORT -s15000 -osubject -eUNZIP -d %a %f
  649.  
  650.  
  651.   -l<file> log file name
  652.  
  653.     Log processing information to <file>. The default is no logging.
  654.  
  655.  
  656.  
  657.   PacketSorter v1.4                                         page 13/19
  658.  
  659.  
  660.  
  661.  
  662.   -d<dir>  directory where packets are searched 
  663.  
  664.     Specify dir as the directory where PacketSorter finds FidoNet packets
  665.     to process. Default is the current directory. Be careful if you use
  666.     this option. Squish for example will unpack packet files to the
  667.     current (Squish) directory. It should not be necessary to use this
  668.     option if you let your echomail tosser call PacketSorter (except when
  669.     using FastEcho).
  670.  
  671.  
  672.   -h       help
  673.  
  674.     Display a short help.
  675.  
  676.  
  677.  
  678.   [program-with-args]exec. archiver before processing
  679.  
  680.     Execute  a  program  (with   optional  arguments)  before  processing
  681.     packets. Only packets that  are created by that  program will then be
  682.     processed by PacketSorter. If  the program returns  another code than
  683.     zero, PacketSorter will not process packets. The program will usually
  684.     be an  archives  extraction  program like  unzip.  You  can  let your
  685.     echomail tosser  call  PacketSorter by  specifiying  PKTSORT  as your
  686.     archives extractor  and  using the  actual  archives  processor (with
  687.     options) as  program-with-args.  See "Quick  installation  for Squish
  688.     users"  for   examples.  If   program-with-args  is   not  specified,
  689.     PacketSorter will  process  all  FTS-0001  packets  it  finds in  the
  690.     current directory or that one specified by  -d. This is useful if you
  691.     receive uncompressed packets and  run PacketSorter from  a batch file
  692.     before calling the tosser. See also option -e.
  693.  
  694.  
  695.   8. Setting the options via an environment variable
  696.   --------------------------------------------------
  697.  
  698.   You may  specifiy  the  options  for  PacketSorter  in the  environment
  699.   variable PKTSORT.  This  is  useful if  you  run  PacketSorter  from an
  700.   archiver entry of an echomail processor and the entry field size is too
  701.   short to include all options you would  like to specify. The format and
  702.   syntax is the same as if the options  are given at the command-line. If
  703.   you specify the options via the environment *and* the command line, the
  704.   command line  options  will  overwrite  the  options  specified in  the
  705.   environment, as  long as  [program-with-args] is  not specified  in the
  706.   environment. If  [program-with-args] is  specified in  the environment,
  707.   all command  line  option  are  treated  as  additional parameters  for
  708.   [program-with-args].
  709.  
  710.   Example:
  711.  
  712.   SET PKTSORT=-s15000 -lc:\logs\pktsort.log
  713.  
  714.   pktsort unzip -n %a %f
  715.  
  716.  
  717.  
  718.   PacketSorter v1.4                                         page 14/19
  719.  
  720.  
  721.  
  722.   is the same as
  723.  
  724.   pktsort -s15000 -lc:\logs\pktsort.log unzip -n %a %f
  725.  
  726.  
  727.   9. Setting the options via a configuration file
  728.   -----------------------------------------------
  729.  
  730.   The configuration file consits of lines starting with a keyword
  731.   followed by a value. All lines not starting with a keyword are
  732.   considered comments. Keywords never start with a semicolon and it is
  733.   good style to preceed comment lines with a semicolon.
  734.  
  735.   There is a 1-to-1 correspondence between the command line options and
  736.   the keywords in the configuration file, so I just present a list of the
  737.   keywords with the corresponding command line option instead of
  738.   repeating all the information contained in the section 'Command line
  739.   options'.
  740.  
  741.   Keyword            command line option      possible values
  742.   -------            -------------------      ---------------
  743.   MessageWindowSize  -w                       1 - 4294967295
  744.   SplitMessages      -s                       8000 - 4294967295
  745.   SplitPackets       -p                       1 - 4294967295
  746.   SortMessagesBy     -o                       Subject or Time
  747.   RemoveGarbage      -g                       0 - 4294967295
  748.   LogFile            -l                       any valid path\file
  749.   PacketDirectory    -d                       any valid directory
  750.   DefaultArchiver    -e                       any valid Archiver entry
  751.   key
  752.  
  753.   The keyword "Archiver" has no corresponding command line option. An
  754.   Archiver entry (definition) in the configuration file looks like this:
  755.  
  756.   Archiver KEY path-and-filename
  757.  
  758.   eg.
  759.  
  760.   Archiver UNZIP c:\packer\unzip.exe
  761.  
  762.   There may be as many Archiver definitions as you like. See option -e
  763.   for details.
  764.  
  765.  
  766.   The file 'pktsort.cfg' is a sample configuration file.
  767.  
  768.  
  769.   10. Packets recognized and created
  770.   ----------------------------------
  771.  
  772.   PacketSorter  will  process  those  packets   that  have  the  filename
  773.   extension .pkt and that have a valid packet id in the packet header.
  774.  
  775.  
  776.  
  777.   PacketSorter v1.4                                         page 15/19
  778.  
  779.  
  780.   PacketSorter merges all  packets that originate  from the  same node or
  781.   point and contain  the same password.  The name of  the packets created
  782.   will be of the  form ????????.PKT, where ????????  is the creation time
  783.   according to FSC-0015.
  784.  
  785.   PacketSorter uses a  hashing technique to  perform the defragmentation.
  786.   So there  is no  'real' sorting  done  and the  defragmented  areas are
  787.   unordered. The order of the messages  within an area remains unchanged,
  788.   unless the options -otime or -osubject are used.
  789.  
  790.  
  791.   11. Return codes
  792.   ----------------
  793.  
  794.   PacketSorter returns the return code of  the program executed (program-
  795.   with-args)  or  zero.  If  PacketSorter  encounters  any  problem,  the
  796.   original packets  are  retained and  the  tosser may  try  to  toss the
  797.   undefragmented packets.
  798.  
  799.  
  800.   12. Disk space consumption
  801.   --------------------------
  802.  
  803.   PacketSorter  needs  exactly  as  much  additional  disk  space  as  is
  804.   occupied by the packets to process.  This is needed because of security
  805.   reasons.
  806.  
  807.  
  808.   13. Removing garbage from packets
  809.   ---------------------------------
  810.  
  811.   This section is for those who want to understand how garbage is removed
  812.   from packets by PacketSorter in detail.
  813.  
  814.   A (proper) FidoNet FTS-0001 packet consists of a packet header, zero or
  815.   more packed messages and an end-of-packet  marker. The packet header is
  816.   identified by a  packet ID and  is not  of real  interest here, because
  817.   PacketSorter does not  process packets  with an invalid  packet header.
  818.   The packed messages consist  of a packed message  header and four zero-
  819.   terminated strings which  contain the originator  name, the destination
  820.   name, the subject  and the message  text. The packed  message header is
  821.   identified by a packed message ID.
  822.  
  823.   Without specifying -g<size>,  PacketSorter considers  those messages as
  824.   being valid, that have  a correct packed message  ID, a correctly sized
  825.   date field (non-FTS  one-space format is  corrected on  the fly without
  826.   notification) and the  from-name, to-name  and subject not  longer than
  827.   FTS-0001 allows. The  message ID  is the  first two  bytes of  a packed
  828.   message. If a previous  message is not properly  terminated, i.e. there
  829.   are some  extra  bytes following  the  last of  the  four  strings, the
  830.   correct message ID cannot be detected  and you'll get the error message
  831.   'invalid packed message header, skipping packets from...'.
  832.  
  833.  
  834.  
  835.   PacketSorter v1.4                                         page 16/19
  836.  
  837.  
  838.   Now, if -g<size> is  specified, PacketSorter tries to  repair a grunged
  839.   date field and  truncates too long  from-name, to-name  and subject. If
  840.   one of these is  truncated, from-name, to-name and  subject must not be
  841.   empty and  the message  text must  be longer  than  one byte,  else the
  842.   message will be deleted. If this fails, PacketSorter skips bytes in the
  843.   packet until  a  vaild packed  message  header is  found.  If  the next
  844.   (potential) message  is  found this  way,  PacketSorter is  a  bit more
  845.   restrictive as to  the contents of  this message, because  I don't want
  846.   PacketSorter to  turn "real  garbage" into  messages. The  message must
  847.   start with a packed  message ID (of course),  contain a valid date/time
  848.   field (one or  two spaces format)  and the  lengths of  the first three
  849.   strings must conform to FTS-0001. If one  of these criteria is not met,
  850.   PacketSorter continues skipping bytes  in search for  the next (proper)
  851.   message.
  852.  
  853.   Grunged date repair goes like that: If  it is one-space format, it will
  854.   be corrected  to  two-space format.  If  it is  shorter  than one-space
  855.   format + 2,  longer than 6  characters and  is accepted  by the regular
  856.   expression [0-9A-Za-z:.- ]+  it will  be replaced by  1-1-80. If  it is
  857.   longer than  two-space format  it is  considered uncorrectable  and the
  858.   message will be invalid.
  859.  
  860.   Additionally, PacketSorter continues searching  for messages beyond the
  861.   end of  packet  marker if  the  physical end  of  the file  is  not yet
  862.   reached. In this  case, the  end of  packet marker  is just  treated as
  863.   "garbage". This has a recovery effect because other software might stop
  864.   processing messages  beyond  the  end  of  packet  marker, thus  losing
  865.   messages.
  866.  
  867.   A missing end of  packet marker at the  physical end of  the file (i.e.
  868.   because the packet has been truncated) will be ingnored.
  869.  
  870.   Messages that passed  PacketSorter but contain  other "dangerous" data,
  871.   such as missing or too long origin lines or non ASCII characters in the
  872.   message text may still  confuse other software. If  you want additional
  873.   protection against such messages, you could run GMD (which is great) on
  874.   the packets before or after they have been processed by PacketSorter.
  875.  
  876.  
  877.  
  878.   14. Technology
  879.   --------------
  880.  
  881.   PacketSorter is  written  in C++  and  compiled with  GNU  GCC. Runtime
  882.   system is EMX  for XMS and  VCPI operation and  RSX for  operation as a
  883.   DPMI client. PacketSorter runs  both under OS/2 and  DOS in 32-BIT flat
  884.   memory model.
  885.  
  886.  
  887.   15. What is different in the registered version
  888.   -----------------------------------------------
  889.  
  890.   The unregistered  version says  that it  is  unregistered and  it beeps
  891.   between 20:00 and 20:59. The registered version does not do this.
  892.  
  893.  
  894.  
  895.   PacketSorter v1.4                                         page 17/19
  896.  
  897.  
  898.  
  899.   16. Other operating systems
  900.   ---------------------------
  901.  
  902.   PacketSorter might  be used  on other  operating  systems than  DOS and
  903.   OS/2, as long as they run  on an i386 (or higher). If  you choose to go
  904.   that way you are probably on your own, as several questions may arise I
  905.   cannot answer  (eg. how  do I  call  a native  MS-Windows  program from
  906.   within Squish running in MS-Windows DOS emulation).
  907.  
  908.   Also note that you must not  distribute PacketSorter in another form as
  909.   in  the   original  distribution   archives.  If   you  come   up  with
  910.   PacketSorter for another  opertating system,  you may  use it  only for
  911.   your own purposes.
  912.  
  913.  
  914.   native MS-Windows
  915.  
  916.     If you'd like to run PacketSorter  as a native MS-Windows application
  917.     (rather than  in  Windows'  DOS  emulation)  get  the archives  named
  918.     rsxwin2a.zip  from   the  FTP-server   ftp.uni-bielefeld.de   in  the
  919.     directory  /pub/systems/msdos/misc. RSXWIN is free software by Rainer
  920.     Schnittker.
  921.  
  922.     Follow  the  instructions   contained  in   that  archives   to  make
  923.     PacketSorter run as a native  MS-Windows application. (Simply execute
  924.     'RSXWIN.EXE -e PKTSORT.EXE [options]'.) When I tried it, it seemed to
  925.     work pretty good.
  926.  
  927.  
  928.   Linux/Unix/Nextstep
  929.  
  930.     If you are a programmer: the  distribution archives contain the files
  931.     needed to  link  the  PacketSorter executable  (except  for  some FSF
  932.     libraries) in the sub-archives devobj.zip. Maybe you are able to link
  933.     the .o files under Linux or other  operating systems using an i386. I
  934.     never tried this, but if  you do, I'd be  interested in hearing about
  935.     your experiences.
  936.  
  937.  
  938.   17. Author
  939.   ----------
  940.  
  941.   The autor of PacketSorter is Rolf K. Wilms. He may be contacted via
  942.  
  943.   Fidonet:      Rolf Wilms@2:2447/107.8
  944.                      or
  945.                 Rolf Wilms@2:2445/10.9 (R24-Classic)
  946.  
  947.   Internet:     rwilms@kottan.bo.open.de
  948.  
  949.  
  950.   Fido via Internet:
  951.  
  952.                 Write a netmail to UUCP@1:105/42
  953.  
  954.  
  955.  
  956.   PacketSorter v1.4                                         page 18/19
  957.  
  958.  
  959.  
  960.                 and make the following line the FIRST line in
  961.                 the message text:
  962.  
  963.                 to: rwilms@kottan.bo.open.de
  964.  
  965.  
  966.   Mail:         Rolf K. Wilms,
  967.                 Franziskastr. 44a,
  968.                 45131 Essen,
  969.                 Germany
  970.  
  971.   Comments and bug reports are welcome.
  972.  
  973.  
  974.   18. Contents of the distribution archives
  975.   -----------------------------------------
  976.  
  977.   The original distribution archives of PacketSorter contains the
  978.   following files:
  979.  
  980.       pktsort.doc    this file
  981.       license.doc    PacketSorter copying and usage license
  982.       order.frm      how to get your registration key
  983.       pktsort.exe    PacketSorter executable for DOS and OS/2
  984.       register.exe   program that turns PKTSORT.EXE into the 
  985.                           registered version (you need a 'key', see 
  986.                                license.doc and order.frm)
  987.       pktsort.cfg    sample configuration file
  988.       emx.exe        EMX runtime module for DOS
  989.       emx.dll        EMX runtime module for OS/2
  990.       emxrt.doc      Advanced installation information for EMX
  991.       rsx.exe        DPMI compliant DOS-extender
  992.       file_id.diz    a small description of PacketSorter
  993.       desc.sdi       an even smaller description of PacketSorter
  994.       history.doc    what has been done
  995.       upgrade.doc    upgrading PacketSorter from earlier versions
  996.       devobj.zip     contains the files needed to link a new
  997.                      PKTSORT executable
  998.       otherlic.zip   contains licenses of the free software used by
  999.                      or aggregated with PacketSorter.
  1000.  
  1001.   The sub archives otherlic.zip contain the following files:
  1002.  
  1003.       copying        GNU General Public License
  1004.       copying.lib    GNU General Public Library License
  1005.       copying.emx    EMX Copying License
  1006.       copying.rsx    RSX Copying License
  1007.  
  1008.   The sub archives devobj.zip contain the following files:
  1009.  
  1010.      hash.o, makefile.pst, mkkey.o, offset.cc, pktsort.o, readme.dev,
  1011.      reginfo.h, register.cc
  1012.  
  1013.  
  1014.  
  1015.   PacketSorter v1.4                                         page 19/19
  1016.  
  1017.  
  1018.   19. Thanks
  1019.   ----------
  1020.  
  1021.   Thanks to Peter Scheffer, Peter Kaszanics,  Robert Dahlem and Johann H.
  1022.   Addicks for their suggestions and for testing PacketSorter.
  1023.